package org.convallaria.system.biz.service.sys;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.service.IService;
import org.convallaria.system.biz.entity.SysDept;

import java.util.List;
import java.util.Set;

/**
 * 系统部门服务接口
 * 
 * 功能特性：
 * - 部门基础CRUD操作
 * - 部门树结构管理
 * - 部门权限管理
 * - 部门角色关联管理
 * - 部门缓存管理
 * 
 * @author convallaria
 * @since 1.0.0
 */
public interface SysDeptService extends IService<SysDept> {

    /**
     * 分页查询部门列表
     * 
     * @param pageNum 页码
     * @param pageSize 页大小
     * @param deptName 部门名称（可选）
     * @param status 状态（可选）
     * @param tenantId 租户ID（可选）
     * @return 部门分页列表
     */
    IPage<SysDept> pageDepts(Integer pageNum, Integer pageSize, String deptName, String status, Long tenantId);

    /**
     * 根据部门ID获取部门信息（带缓存）
     * 
     * @param deptId 部门ID
     * @return 部门信息
     */
    SysDept getDeptById(Long deptId);

    /**
     * 获取部门树结构
     * 
     * @param tenantId 租户ID
     * @return 部门树列表
     */
    List<SysDept> getDeptTree(Long tenantId);

    /**
     * 根据父部门ID获取子部门列表
     * 
     * @param parentId 父部门ID
     * @param tenantId 租户ID
     * @return 子部门列表
     */
    List<SysDept> getChildrenDepts(Long parentId, Long tenantId);

    /**
     * 获取用户部门树
     * 
     * @param userId 用户ID
     * @param tenantId 租户ID
     * @return 用户部门树
     */
    List<SysDept> getUserDeptTree(Long userId, Long tenantId);

    /**
     * 获取角色的部门权限
     * 
     * @param roleId 角色ID
     * @param tenantId 租户ID
     * @return 部门权限列表
     */
    List<SysDept> getRoleDepts(Long roleId, Long tenantId);

    /**
     * 更新部门信息（清除相关缓存）
     * 
     * @param dept 部门信息
     * @return 是否成功
     */
    boolean updateDept(SysDept dept);

    /**
     * 删除部门（清除相关缓存）
     * 
     * @param deptId 部门ID
     * @return 是否成功
     */
    boolean deleteDept(Long deptId);

    /**
     * 批量删除部门（清除相关缓存）
     * 
     * @param deptIds 部门ID列表
     * @return 是否成功
     */
    boolean deleteDepts(List<Long> deptIds);

    /**
     * 刷新部门缓存
     * 
     * @param dept 部门信息
     * @return 部门信息
     */
    SysDept refreshDeptCache(SysDept dept);

    /**
     * 获取部门的所有子部门ID
     * 
     * @param deptId 部门ID
     * @return 子部门ID集合
     */
    Set<Long> getDeptChildrenIds(Long deptId);

    /**
     * 获取用户的所有部门权限
     * 
     * @param userId 用户ID
     * @param tenantId 租户ID
     * @return 部门ID集合
     */
    Set<Long> getUserDeptPermissions(Long userId, Long tenantId);

    /**
     * 检查部门名称是否唯一
     * 
     * @param deptName 部门名称
     * @param deptId 部门ID（更新时排除自己）
     * @param parentId 父部门ID
     * @param tenantId 租户ID
     * @return 是否唯一
     */
    boolean isDeptNameUnique(String deptName, Long deptId, Long parentId, Long tenantId);

    /**
     * 检查部门是否有子部门
     * 
     * @param deptId 部门ID
     * @return 是否有子部门
     */
    boolean hasChildrenDepts(Long deptId);

    /**
     * 检查部门是否有用户
     * 
     * @param deptId 部门ID
     * @return 是否有用户
     */
    boolean hasUsers(Long deptId);

    /**
     * 构建部门树结构
     * 
     * @param depts 部门列表
     * @return 部门树列表
     */
    List<SysDept> buildDeptTree(List<SysDept> depts);

    /**
     * 获取部门的完整路径
     * 
     * @param deptId 部门ID
     * @return 部门路径
     */
    String getDeptPath(Long deptId);

    /**
     * 获取部门的层级深度
     * 
     * @param deptId 部门ID
     * @return 层级深度
     */
    int getDeptDepth(Long deptId);

    /**
     * 根据部门编码获取部门
     * 
     * @param deptCode 部门编码
     * @param tenantId 租户ID
     * @return 部门信息
     */
    SysDept getDeptByCode(String deptCode, Long tenantId);

    /**
     * 获取部门的所有父部门
     * 
     * @param deptId 部门ID
     * @return 父部门列表
     */
    List<SysDept> getDeptParents(Long deptId);

    /**
     * 获取部门的所有子部门
     * 
     * @param deptId 部门ID
     * @return 子部门列表
     */
    List<SysDept> getDeptAllChildren(Long deptId);

    /**
     * 检查部门是否在指定部门下
     * 
     * @param deptId 部门ID
     * @param parentId 父部门ID
     * @return 是否在指定部门下
     */
    boolean isDeptUnderParent(Long deptId, Long parentId);
}
